/*
 * This file is part of FauXML.
 * FauXML is free software: you can redistribute it
 * and/or modify it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation, either version 3 of the License,
 * or (at your option) any later version.
 * 
 * FauXML is distributed in the hope that it will be
 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public License
 * along with FauXML.
 * If not, see <http://www.gnu.org/licenses/>.
 */
package com.googlecode.fauxml.parser;

import java.util.List;
import com.googlecode.fauxml.parser.FauXMLParserEngine.Error;
import com.googlecode.fauxml.util.Pair;

/**
 * This class is the callback interface for the FauXMLParserEngine. Users
 * should make their parsers implement this interface, then call the parse
 * method of the FauXMLParserEngine with a reference to the implementor of this
 * interface. The FauXMLParser methods will be invoked as callback methods.
 * @author Andrew Matta
 */
public interface FauXMLParser {
	/**
	 * This method is called by the engine after reading in a starting
	 * tag. The tag name is passed in as a String, while all the attributes
	 * are passed in as a list of Pairs, where the the Pair's key is the
	 * attribute name, and the Pair's value is the attribute value.
	 * 
	 * If this is a singleton tag (e.g. %lt;TAGNAME /&gt;), onStartTag will be
	 * called as usual, and when this returns, onEndTag will be called
	 * immediately afterwards without calling onData in between. Otherwise,
	 * onStartTag will be called, followed by onData, followed by onEndTag.
	 * 
	 * Should this not be a singleton, but there be no data, onData will be
	 * called anyway, but it will just contain an empty String.
	 * 
	 * @param tagName The name of the parsed starting tag
	 * @param attributes A list of attribute Pairs for the parsed starting tag
	 */
	public void onStartTag(String tagName, List<Pair<String, String>> attributes);

	/**
	 * This method is called after a start tag is parsed, and after an end tag
	 * is parsed, but before onEndTag is called. The data String will contain
	 * all characters found between the starting and ending tags, including
	 * whitespace.
	 * 
	 * @param data A String containing all characters between the previous start
	 * tag and the next end tag
	 */
	public void onData(String data);

	/**
	 * This method is called when a terminating tag has been parsed. It is
	 * passed a string containing the tag's name.
	 * 
	 * @param tagName The name of the end tag that was parsed
	 */
	public void onEndTag(String tagName);

	/**
	 * This method is called by the engine after reading in a processing
	 * instruction (elements starting with '%lt;?' and ending with '?&gt;'.
	 * 
	 * @param instructionName The name of the instruction
	 * @param attributes A list of attribute Pairs for the parsed instruction
	 */
	public void onInstruction(String instructionName, List<Pair<String, String>> attributes);

	/**
	 * This method is called by the engine when an error in parsing occurs and
	 * the parser needs to terminate.
	 * @param error The error causing the termination
	 * @param lineNumber The line in the XML where the parser discovered the problem
	 */
	public void onError(Error error, int lineNumber, int columnNumber);	//TODO: Ditch this. Have ParserEngine throw a specially-made exception instead.

	/**
	 * This method is checked by the engine after any callback returns. The
	 * implementing class should ensure that this method will return false as
	 * long as parsing should continue, and should return true if parsing should
	 * be cancelled (even if parsing is not complete).
	 */
	public boolean abort();	//TODO: Ditch this. Have Parser throw a specially-made exception instead.
}
